.dmg/Serious Software/NetCloak 3.0.3 Pro CD demo.sea/NetCloak 3.0.3 Pro CD demo/NetCloak Introduction/NetCloak/NCProUsersGuide/Figures/NP.GIF){kind=small}
User's Guide
Primary Directives
Contents
|
Version 3.0 Pro User's Guide |
Primary Directives |
Previous |
Next Contents |
The four Primary Directives of NetCloak Pro are designed to perform the following tasks:
The following sections describe these four capabilities, and you are encouraged to refer to the on-line examples to see each of the Primary Directives in action.
The <CREATEDOC> directive tells NetCloak Pro to build a new HTML page and save it as a file specified by the "Filename" parameter, as in the example below. The Filename parameter can be specified as a path relative to the Web server root folder or relative to the FDML document. The proper syntax for the CREATEDOC directive is:
<CREATEDOC>"Filename"</CREATEDOC> New document template...
Frequently the directive will contain other FDML insertion commands (like <REPLACE>, described in the "Commands" section) to build a dynamic filename so that documents are uniquely named on your server and are not overwritten each time a new user fills out your form.
When any of the insertion commands are used in a filename, you should use the "REPLACE_FN" ("FN" stands for "File Name") command. This ensures that characters which are not allowed in file or folder names are removed before new files are created. See the section on the REPLACE command for more information.
When the filename you specify contains path elements that are MacOS aliases to folders, the aliases are resolved automatically. Also, if any folders in the path do not exist, they are created automatically. If you use the <YEAR> or <MONTH> insertion commands in the "Filename" parameter, for example, you can have NetCloak Pro automatically create a new folder for every year and every month, like this:
<CREATEDOC>"Reports/<YEAR>/<MONTH_FN>/MonthlyReport.html"</CREATEDOC>
What follows the closing </CREATEDOC> in the FDML file is text and/or HTML that serves as a template for the document to be created. This template defines the format of the new document, including the standard HTML, header, and body tags (<HTML>...</HTML>, <HEAD>...</HEAD>, and <BODY>...</BODY>). Throughout the document template, you may use FDML insertion commands to dynamically insert form data into the created document. See the on-line demonstration systems for examples of HTML document templates used with the CREATEDOC directive.
Note: FDML syntax is similar to HTML, but is different enough to cause problems when using "WYSIWYG" HTML editing applications like Adobe PageMill or Claris HomePage. If you plan to use such a program to create your document templates, Maxum recommends creating the template using the HTML editor first, until you are satisfied with the page layout. Then open the HTML file using a text editor like SimpleText or BBEdit, and add the FDML directives and insertion commands afterward.
The INSERTFILE directive allows you to insert text into an existing HTML page instead of creating an entirely new page. The syntax is shown below:
<INSERTFILE "MarkerText">"Filename"</INSERTFILE> Text to insert...
There are two parameters used with the INSERTFILE directive.
The first, located within the opening <INSERTFILE> tag, is the text which marks the location within the file where the new text should be inserted. While any text may be used to mark the insertion point in the file, an HTML comment is most often used, so that the insertion point text does not appear in the client's browser.
The second parameter is simply the path and name of the file to be updated and appears between the opening and closing tags.
The syntax of an HTML comment is shown in the following example.
<HTML> <HEAD> <TITLE>Test Document</TITLE> </HEAD> <BODY>
<H1>This is a test document</H1>
<!--EnterText-->
</BODY> </HTML>
To use the <INSERTFILE> directive to update this file, simply specify the HTML comment followed by the file path, like this, in your FDML file. For our example, the file is named "testdoc.html", and is located in a folder named "docs" located in the root folder of the Web server:
<INSERTFILE "<!--EnterText-->"> "/docs/testdoc.html" </INSERTFILE>
Following the closing </INSERTFILE> tag is the text or HTML to be inserted into the new document. As with the CREATEDOC directive, you may use any standard HTML tag and any FDML insertion command in this text to customize it based on the form input data. Since this text will be inserted into an existing HTML document, however, you should not include the HTML, header, and body tags.
Using the basic INSERTFILE directive, new text will be added after the comment, which will cause the new entries to be added to the top of the list of entries, creating a "newest first" listing. Use the variation <INSERTFILE*> to have new entries added before the comment, which will cause the list of entries to grow downward, in a "newest last" format.
The TEXTSTORE directive will store data submitted from a form in a tab-delimited text file without any other formatting. Data from subsequent form submissions are added as the next line of the file.
There will probably be times when you want to create a form to receive user input and use that information in another application. For example, you may want to load the data into a spreadsheet or into your favorite database application. You might also want to store data in a simple format for archival or backup purposes, and go on to process the form with other FDML documents.
In either case, the NetCloak Pro directive TEXTSTORE will handle this for you by creating and maintaining a simple text file. This file can then be imported into the application or database of your choice whenever you need it. What you do with the file is up to you, but virtually all word processing, database, and spreadsheet applications will read it, when configured properly. Most personal information managers and other types of software will read the information as well. The syntax for the TEXTSTORE directive is as follows.
<TEXTSTORE>"TextFileName"</TEXTSTORE> Record format...
The "TextFileName" parameter is simply the name of the file that NetCloak Pro will create and maintain. As with any directive, you may use FDML insertion commands within the parameter to allow multiple files to be created and maintained based on user input. Note that since the created file is not an HTML file, it should not have the ".html" file suffix. Instead, it should have a suffix of ".text" or ".txt", to denote that it is a plain text file.
Following the <TEXTSTORE> directive in the FDML file is the list of fields you would like stored in each record in the text file. Records are separated in the text file by a single carriage return character, and fields within a record are separated by a tab character.
In the FDML file, each field is placed by itself on a line of the FDML file. For example, if you want to allow users to submit their names and e-mail addresses you would create an HTML entry form with two fields, "Name" and "E-mail". The syntax for a very simple FDML document to store data in a file named "Signup.text" would be:
<TEXTSTORE>"Signup.text"</TEXTSTORE> Name
E-mail
This would result in a text file named "Signup.text" (located in the same folder as the FDML file) which might contain the following text after a few users had used the form page:
Chris Patterson chris@maxum.com
John O'Fallon john@maxum.com
Steve Jobs steve@apple.com
You can also specify text constants to be stored in the text file by beginning a line of the FDML file with a plus sign ("+"). This tells NetCloak Pro to insert the text exactly as it appears, without attempting to find user-entered data for that field. Inserting constant text by itself isn't terribly useful, but when used in conjunction with other NetCloak Pro commands, the possibilities grow considerably. For example, we can add a time and date stamp to our "signup" example above, as in the following example:
<TEXTSTORE>"Signup.text"</TEXTSTORE> +Date: <DATE> Time: <TIME> E-mail
Which would result in a text file that looked like this:
Date: 12/14/97 Time: 14:25:27 chris@maxum.com
Date: 12/15/97 Time: 08:42:18 john@maxum.com
Date: 12/16/97 Time: 18:02:44 steve@apple.com
The "E-mail" field could also be labeled, as in the following example:
<TEXTSTORE>"Signup.text"</TEXTSTORE> +Date: <DATE> Time: <TIME> +E-Mail: <REPLACE Email>
Resulting in:
Date: 12/14/97 Time: 14:25:27 E-Mail: chris@maxum.com
Date: 12/15/97 Time: 08:42:18 E-Mail: john@maxum.com
Date: 12/16/97 Time: 18:02:44 E-Mail: steve@apple.com
TEXTSTORE FDML files are completely parsed, so you can use all FDML insertion commands, including IF commands, within TEXTSTORE documents. The IF command can be used effectively within TEXTSTORE documents to selectively insert user responses based on the contents of other fields. In addition, you can specify text to be inserted into the data file "as is". Use the plus sign ("+") to tell NetCloak Pro "This isn't a user-entered field, it's just some text you should put into the file." See the TextDemo example included in this package for additional information on how this works.
Note: Using "WYSIWYG" HTML editors such as Adobe PageMill or Claris Home Page to create TEXTSTORE FDML files is not recommended by Maxum. This is simply because the TEXTSTORE directive does not create an HTML file - it creates a plain text file. Therefore, it should not contain HTML tags of any kind. Only FDML insertion commands and field names should be used in the record formatting portion of the FDML file.
NetCloak Pro is capable of sending e-mail messages using Simple Mail Transfer Protocol (SMTP). This command uses threaded, native Open Transport calls for greater speed, but is also compatible with Mac OS versions that use MacTCP. An HTML response file is sent to users before e-mail has been completely sent, so errors in e-mail transmission may not be displayed to the user. To ensure that mail is never lost, NetCloak Pro saves each mail message as a file on the server until it is sent.
When a form is submitted, NetCloak Pro can build an e-mail message and send it to anyone you like. As the author of the HTML entry form, you control which user-entered fields are included in the message and the format of the message. The SENDMAIL syntax is:
<SENDMAIL "server" "to" "from" "cc"> subject
</SENDMAIL>
Message to send...
Within the <SENDMAIL> tag, you specify four parameters, described below.
To reduce the chances of failure, you should use the closest (and most stable) e-mail server available to you.
If you aren't sure of the address of your e-mail server, check your Internet e-mail client software configuration or ask your ISP or network administrator.
You may specify multiple e-mail recipients in this parameter by separating the e-mail addresses with a comma, like this: "bob@company.com, fred@company.com, jill@company.com".
For each recipient, you may also include the user's real name, like this: "Bob Smith bob@company.com, Fred Jones fred@company.com, Jill Johnson jill@company.com".
Finally, for each e-mail address, you may use double-quote characters to mark text that is to be ignored by the SMTP mail server when parsing the address, such as the real name. But because double-quote characters are also used to delimit the "to" address parameter, you must use "double-double-quotes" to "escape" the embedded double-quote characters within the SENDMAIL tag. For example:
<SENDMAIL ... """Chris S. Patterson"" chris@maxum.com" ... >
See the "BetterMailDemo" system for an example.
NetCloak Pro insertion commands can be used to dynamically set the "to" parameter.
Immediately following the <SENDMAIL> tag is the message subject. This is the phrase that will be used as the subject of the e-mail message. This is followed by the closing </SENDMAIL> tag. As with any directive parameter, NetCloak Pro Insertion Commands, like <REPLACE>, can be used to dynamically create a subject line.
Anything after the </SENDMAIL> tag will be sent in the body of the message. A combination of plain text and NetCloak Pro insertion commands may be used to customize the body of the message from the input form data.
The content type of the mail message is normally plain text, which is the default content type, and is supported by all e-mail client software. However, you can send a message with HTML-formatted content. NetCloak Pro will set the content type of the mail message to "text/html" if the very first text of the message, other than space characters, is the "<HTML>" tag. This allows HTML-formatted mail messages to be displayed properly by e-mail clients, such as Netscape Communicator, that can handle them.
Using NetCloak Pro to send e-mail is very simple and is almost always set up in much the same way, so an example will make things clearer and is always a good place to start. For this example, we have an HTML form that accepts the following fields from the user: "Email", "Subject", "UserName", "Phone", and "Message". The FDML would look like this:
<RESPONSE>"/MailDemo/Response.html"</RESPONSE>
<SENDMAIL
"mail.yourorg.com"
"John Smith john@mail.yourorg.com"
"<REPLACE UserName> <REPLACE Email>"> <REPLACE Subject> </SENDMAIL>
Name: <REPLACE UserName> E-Mail Address: <REPLACE Email> Phone Number: <REPLACE Phone> Message:
<REPLACE Message>
Here we've used a <RESPONSE> directive prior to the <SENDMAIL> directive to allow a predetermined HTML page to be returned to a user after the <SENDMAIL> form is submitted. The <SENDMAIL> directive then specifies exactly how to send the message, including SMTP host, sender, recipient (obtained from the person filling in the form), and subject (also obtained from the form). In this case, NetCloak Pro will use the server "mail.yourorg.com" to send a message to John Smith. The message will be "from" the person that filled out the form, so when John uses his e-mail client to "reply" to the message, the reply will be automatically sent to the correct address.
Note that using <REPLACE> commands within the <SENDMAIL> directive is perfectly legal, and sometimes essential. Finally, following the <SENDMAIL> directive is the body of the message (which is also obtained from the form that has been completed).
See the "MailDemo" and "BetterMailDemo" systems in the NetCloak Pro release package.
If the message is sent successfully, the mail file is deleted.
If the message cannot be sent, the mail file is updated with a retry count and an error message that explains the reason the message could not be sent. Common reasons that mail messages fail to be sent are:
NetCloak Pro will retry to send mail messages up to five times. After the fifth failed attempt, the corresponding mail file is moved from the "NetForms Mail Queue" folder into another folder named "NetForms Failed Mail" inside the "NetCloak Files" folder. This is the electronic equivalent of the "dead-letter" bin at your post office. Once moved, these files are ignored by NetCloak Pro.
Periodically, the NetCloak Pro administrator should check the contents of the "NetForms Failed Mail" folder. Some failed mail messages can be easily fixed by editing the mail file (they are simple TEXT files) and "re-queuing" them by moving them back to the "NetForms Mail Queue" folder. Other failed mail files may be simply dragged to the Trash to reclaim disk space.
Hot tip: Because NetCloak Pro looks for text files in the "NetForms Mail Queue" folder to send email messages, any application or AppleScript that can create text files can also use NetCloak Pro to send email messages! The text file created need only conform to the format of NetCloak Pro-generated mail files in order for NetCloak Pro to be able to send a message.
| Copyright © 1996-1999 Maxum Development Corporation http://www.maxum.com/ |
Previous |
Next Contents |